/*******************************************************************************
 * Copyright (c) 2009 Markus Knittig and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     Markus Knittig - initial API and implementation
 *******************************************************************************/
package com.googlecode.mylyn.core.client;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;

import com.google.gdata.client.projecthosting.IssuesQuery;
import com.google.gdata.data.Person;
import com.google.gdata.data.projecthosting.IssueCommentsEntry;
import com.google.gdata.data.projecthosting.IssueCommentsFeed;
import com.google.gdata.data.projecthosting.IssuesEntry;
import com.google.gdata.data.projecthosting.IssuesFeed;

/**
 * Interface to directly access google code issue repositories.
 * 
 * <p>The methods that take a monitor (all in the IO category) all do IO, so
 * don't call them in the UI thread. They never return {@literal null} but may
 * throw an Exception.</p>
 * 
 * <p>The methods that don't take a monitor (all in the memory category) will
 * not do any IO.</p>
 */
public interface IGoogleCodeClient {

    /**
     * Gets all the issues of a project. This method does IO so don't call it
     * in the UI thread.
     * 
     * @category IO
     * @param monitor the monitor to use for reporting progress
     * @return all the issues of a project
     * @throws CoreException if fetching all issues fails
     */
    IssuesFeed getAllIssues(IProgressMonitor monitor) throws CoreException;
    
    /**
     * Gets all the issues of a project for a given query. This method does IO
     * so don't call it in the UI thread.
     * 
     * @category IO
     * @param query the query
     * @param monitor the monitor to use for reporting progress
     * @return all the issues of a project
     * @throws CoreException if fetching all issues fails
     */
    IssuesFeed getQueryIssues(IssuesQuery query, IProgressMonitor monitor) throws CoreException;
    
    /**
     * Gets the issue with the given id. This method does IO so don't call it
     * in the UI thread.
     * 
     * @category IO
     * @param issueId the id of the issue to get
     * @param monitor the monitor to use for reporting progress
     * @return all the issues of a project
     * @throws CoreException if fetching all issues fails
     */
    IssuesEntry getEntry(String issueId, IProgressMonitor monitor) throws CoreException;
    
    /**
     * Gets comments of the issue with the given id. This method does IO so
     * don't call it in the UI thread.
     * 
     * @category IO
     * @param issueId the id of the issue who's comments to get
     * @param monitor the monitor to use for reporting progress
     * @return all the comments of the issue
     * @throws CoreException if fetching all comments fails
     */
    IssueCommentsFeed getAllComments(String issueId, IProgressMonitor monitor) throws CoreException;

    /**
     * Creates a issue. This method does IO so don't call it in the UI thread.
     * 
     * @category IO
     * @param summary the summary of the issue to create
     * @param description the description of the issue to create
     * @param monitor the monitor to use for reporting progress
     * @return the newly created issue
     * @throws CoreException if creating the comment fails
     */
    IssuesEntry createIssue(IssuesEntry entry, IProgressMonitor monitor) throws CoreException;
    
    /**
     * Updates an issue by post a comment that contains updates. If the comment
     * doesn't contain updates it simply posts is without making any updates to
     * the issue itself. This method does IO so don't call it in the UI thread.
     * 
     * @see com.google.gdata.data.projecthosting.Updates
     * @category IO
     * @param issueId the id of the issue for whom to create a comment
     * @param summary the new summary of the issue
     * @param monitor the monitor to use for reporting progress
     * @return the newly created issue
     * @throws CoreException if creating the comment fails
     */
    IssueCommentsEntry updateIssue(String issueId, IssueCommentsEntry entry, IProgressMonitor monitor)
    throws CoreException;
    
    /**
     * Creates a new blank and valid issues query for this repository. This
     * method doesn't do IO so it's safe to call it in the UI thread. 
     * 
     * @category memory
     * @return a new blank and valid issues query for this repository
     */
    IssuesQuery createNewIssuesQuery();
    
    /**
     * Returns the current repository user. This method doesn't do IO so it's
     * safe to call it in the UI thread. 
     * 
     * @category memory
     * @return the current repository user
     */
    Person getCurrentUser();
    
    /**
     * Creates a fully qualified issue id from a numeric issue id. This method
     * doesn't do IO so it's safe to call it in the UI thread. 
     * 
     * @see com.google.gdata.data.IAtom#setId(String)
     * @category memory
     * @param issueId the numeric issue id, eg. {@literal 42}
     * @return a fully qualified issue id
     */
    String createIssueId(String issueId);
    
}
